/**
 * @file tool_path_planner.h
 * @copyright Copyright (c) 2021, Southwest Research Institute
 *
 * @par License
 * Software License Agreement (Apache License)
 * @par
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * @par
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#pragma once
// `#pragma once` 是一种预处理指令，表示该头文件在编译过程中只会被包含一次，避免重复包含。

#include <memory>
// 引入 C++ 标准库中的 memory 头文件，用于智能指针等内存管理功能。

#include <pcl/PolygonMesh.h>
// 引入 Point Cloud Library (PCL) 中的 PolygonMesh 类，通常用于表示多边形网格。

#include <noether_tpp/core/types.h>
// 引入自定义库（`noether_tpp`）中的类型定义文件，用于工具路径规划（Tool Path Planning）。

namespace noether
{
// `noether` 命名空间用于组织代码，避免名称冲突。

/**
 * @brief Interface for a tool path planner that operates on a mesh.
 */
// ToolPathPlanner 接口用于描述基于网格的工具路径规划器。
struct ToolPathPlanner
{
  // 定义智能指针类型，以便在类外引用时使用。
  using Ptr = std::unique_ptr<ToolPathPlanner>;
  // `Ptr` 是指向 ToolPathPlanner 对象的 `std::unique_ptr`（独占智能指针），用于自动管理内存。
  
  using ConstPtr = std::unique_ptr<const ToolPathPlanner>;
  // `ConstPtr` 是指向常量 ToolPathPlanner 对象的智能指针。

  virtual ~ToolPathPlanner() = default;
  // 虚析构函数，用于确保正确销毁派生类对象。

  virtual ToolPaths plan(const pcl::PolygonMesh& mesh) const = 0;
  // 纯虚函数 `plan`，用于执行工具路径规划。
  // 接收一个 PCL 的 PolygonMesh 对象（表示多边形网格），返回一个 ToolPaths 类型的路径集合。
  // 该函数是接口的一部分，具体实现需要在派生类中定义。
};

/**
 * @brief Interface for creating implementations of the tool path planner interface
 */
// ToolPathPlannerFactory 接口用于创建 ToolPathPlanner 的具体实现。
struct ToolPathPlannerFactory
{
  virtual ~ToolPathPlannerFactory() = default;
  // 虚析构函数，确保正确销毁工厂对象。

  virtual std::unique_ptr<const ToolPathPlanner> create() const = 0;
  // 纯虚函数 `create`，用于创建一个 ToolPathPlanner 的具体实现。
  // 返回一个常量智能指针 `std::unique_ptr<const ToolPathPlanner>`，表示返回的对象是一个不可修改的 ToolPathPlanner 实例。
};

}  // namespace noether
// `noether` 命名空间结束。

